Unity SDK 使用指南

本指南将会介绍如何使用 Unity SDK 接入您的项目。建议在接入开始前，先阅读数据规则一章。您可以在访问GitHub获取Unity SDK的源代码。

最新版本为：1.3.0

更新时间为：2019-10-22

下载地址

1. 初始化 SDK

1.1 集成 SDK

下载Unity SDK资源文件，并导入资源文件到您的项目中：Assets > Import Package > Custom Package，选中您刚刚下载的文件

注意：Android 插件使用 Gradle 集成，因此目前只支持 Unity 5.4 之后的版本。
添加 ThinkingAnalytics GameObject，并设置 SDK 配置

上图中的配置分别为：

Configuration

Enable Log：是否开启日志，若开启，则会打印上报情况，以方便您的调试。您也可以在 Editor 模式下，检验事件上报是否正确，对于不符合条件的属性，会以warning日志显示在控制台中。
Network Type：设置上报数据到服务器的网络条件，默认为DEFAULT，以下是所有可选项及对应说明
- DEFAULT：3G, 4G, 5G 及 WIFI环境下上报数据
- WIFI：只在 WIFI 环境下上报数据
- ALL：2G, 3G, 4G, 5G 及 WIFI环境下上报数据
Postpone Track：设置是否延迟上报，开启该选项后，数据将会在调用StartTrack()后才开始上报，调用前数据将会被缓存，直到StartTrack()被调用。如果您需要设置访客ID或者公共属性，建议您开启此项，调用请参考延迟上报部分

Project

Server Url：需要进行配置，为数据上传的URL
- 如果您使用的是云服务，请输入以下URL:
  - http://receiver.ta.thinkingdata.cn
  - 或 https://receiver.ta.thinkingdata.cn
- 如果您使用的是私有化部署的版本，请输入以下URL:
  - http://数据采集地址

Tokens：
- APP ID：需要进行配置，您的项目的APP_ID，在您申请项目时会给出，请在此处填入。如需向多个项目上报数据，可点击右下角“+”号增加项目，多项目的注意事项请参考节末的"多项目支持"一节
- Auto Track：是否开启自动采集事件，如果勾选了，则 SDK 会自动记录游戏的启动以及关闭，详情请参考自动采集事件

多项目支持

在配置 SDK 时，可以添加多个 APP ID，之后在调用 API 时，最后附加一个参数指定 APP ID，以 Identify() 接口为例：

// 为 APP ID 为 “debug-appid” 的APP ID实例设置访客 ID
ThinkingAnalyticsAPI.Identify("unity_debug_id", "debug-appid");

注意：访客 ID、账户 ID、公共属性等在多项目中不共享，需要为每个APP ID实例单独进行设置

如果没有附加 APP ID 参数，则默认使用列表中第一个 APP ID实例（Token ID后有default标识的实例）。您可以通过拖动列表项的方式调整列表顺序，以此调节默认的APP ID实例。

1.2 使用 SDK

当您完成了SDK配置后，就可以开始使用 SDK 上传事件了，我们也提供了 Sample 供您参考。

using ThinkingAnalytics;

ThinkingAnalyticsAPI.Track("unity_start");

2. 设置用户 ID

在使用Unity SDK之后，SDK会使用UUID作为每个用户的默认访客ID，该ID将会作为用户在未登录状态下身份识别ID。需要注意的是，默认访客ID会在用户重新安装APP以及更换设备时将会变更。

a) 设置访客ID（可选）

如果您的 APP 对每个用户有自己的访客ID管理体系，则您可以调用Identify来设置访客 ID:

ThinkingAnalyticsAPI.Identify("unity_id");

如果需要获得访客 ID，可以调用GetDistinctId获取：

ThinkingAnalyticsAPI.GetDistinctId();

b) 设置与清除账号 ID

在用户进行登录时，可调用Login来设置用户的账号 ID，在设置完账号 ID 后，将会以账号 ID 作为用户标识 ID，并且设置的账号 ID 将会在调用Logout之前一直保留：

// 设置账号 ID
ThinkingAnalyticsAPI.Login("unity_user");

// 清除账号 ID
ThinkingAnalyticsAPI.Logout();

注意：该方法不会上传用户登录、用户登出等事件。

3. 上传事件

通过ThinkingAnalyticsAPI.Track() 可以上报事件及其属性。一般情况下，您可能需要上传十几到上百个不同的事件，如果您是第一次使用 TDA 后台，我们推荐您先上传几个关键事件。

3.1 上传事件

建议您根据先前梳理的文档来设置事件的属性以及发送信息的条件。事件名称是string类型，只能以字母开头，可包含数字，字母和下划线“_”，长度最大为50个字符，对字母大小写不敏感。

Dictionary<string, object> properties = new Dictionary<string, object>()
    {
        {"KEY_DateTime", DateTime.Now.AddDays(1)},
        {"KEY_STRING", "B1"},
        {"KEY_BOOL", true},
        {"KEY_NUMBER", 50.65}
    };
ThinkingAnalyticsAPI.Track("TEST_EVENT", properties);

事件属性是Dictionary<string, object> 类型，其中每个元素代表一个属性；
事件属性Key为属性名称，为string类型，规定只能以字母开头，包含数字，字母和下划线“_”，长度最大为50个字符，对字母大小写不敏感；
属性值支持四种类型：字符串、数值类、bool、DateTime。

当您调用 Track() 时，SDK 会取系统当前时间作为事件发生的时刻，如果您需要指定事件时间，可以传入DateTime类型的参数来设置事件触发时间，v1.3.0版本开始，SDK 支持根据DataTimeKind上传事件的时间偏移（对应预置属性 #zone_offset），但是如果传入的DateTime的 Kind 属性为 DataTimeKind.Unspecified，则不会上报时间偏移：

DateTime dateTime = DateTime.Now.AddDays(-1);
ThinkingAnalyticsAPI.Track("TEST_EVENT", properties, dateTime);

注意：尽管事件可以设置触发时间，但是接收端会做如下的限制：只接收相对服务器时间在前 10 天至后 4 天的数据，超过时限的数据将会被视为异常数据，整条数据无法入库。

3.2 设置静态公共属性

对于一些重要的属性，譬如玩家的区服和渠道等，这些属性需要设置在每个事件中，此时您可以将这些属性设置为公共事件属性。公共事件属性指的就是每个事件都会带有的属性，您可以调用SetSuperProperties来设置公共事件属性，我们推荐您在发送事件前，先设置公共事件属性。

Dictionary<string, object> superProperties = new Dictionary<string, object>()
    {
        {"SERVER", 0},
        {"CHANNEL", "A3"}
    };
ThinkingAnalyticsAPI.SetSuperProperties(superProperties);

公共事件属性将会被保存到缓存中，无需每次启动APP时调用。如果调用SetSuperProperties上传了先前已设置过的公共事件属性，则会覆盖之前的属性。如果公共事件属性和Track()上传的某个属性的Key重复，则该事件的属性会覆盖公共事件属性。

如果您需要删除某个公共事件属性，您可以调用UnsetSuperProperty()清除其中一个公共事件属性；如果您想要清空所有公共事件属性，则可以调用ClearSuperProperties()

// 清除属性名为 CHANNEL 的公共属性
ThinkingAnalyticsAPI.UnsetSuperProperty("CHANNEL");

// 清空所有公共属性
ThinkingAnalyticsAPI.ClearSuperProperties();

3.3 设置动态公共属性

如果公共属性的值不是常量，您可以通过设置动态公共属性的方式实现。动态公共属性也会加入到所有事件中，在事件上报时会动态获取实际上报值。

设置动态公共属性，需要先新建动态公共属性类并实现 IDynamicSuperProperties 接口，复写public Dictionary<string, object> GetDynamicSuperProperties()方法，该方法的返回值即是需要设置的动态公共属性。再调用SetDynamicSuperProperties传入动态公共属性对象，样例如下：

using ThinkingAnalytics;

// 定义动态公共属性实现，此例为设置 UTC 时间的动态公共属性
public class DynamicProp : IDynamicSuperProperties
{
    public Dictionary<string, object> GetDynamicSuperProperties()
    {
        return new Dictionary<string, object>() {
            {"KEY_UTCTime", DateTime.UtcNow}
        };
    }
}

ThinkingAnalyticsAPI.SetDynamicSuperProperties(new DynamicProp());

如果事件重名，动态公共属性的优先级大于公共事件属性，小于Track中设置的事件属性。

3.4 记录事件时长

您可以调用TimeEvent()来开始计时，配置您想要计时的事件名称，当您上传该事件时，将会自动在您的事件属性中加入#duration这一属性来表示记录的时长，单位为秒。

// 调用 TimeEvent 开启对 TIME_EVENT 事件的计时
ThinkingAnalyticsAPI.TimeEvent("TIME_EVENT");

// do some thing...

// 通过 Track 上传 TIME_EVENT 事件时，会在属性中添加 #duration 属性
ThinkingAnalyticsAPI.Track("TIME_EVENT");

4. 用户属性

TA 平台目前支持的用户属性设置接口为UserSet、UserSetOnce、UserAdd、UserDelete。

4.1 UserSet

对于一般的用户属性，您可以调用UserSet来进行设置，使用该接口上传的属性将会覆盖原有的属性值，如果之前不存在该用户属性，则会新建该用户属性。

ThinkingAnalyticsAPI.UserSet(new Dictionary<string, object>()
    {
        {"USER_PROP_NUM", 0},
        {"USER_PROP_STRING", "A3"}
    });

与事件属性类似：

用户属性是Dictionary<string, object> 类型，其中每个元素代表一个属性；
用户属性Key为属性名称，为string类型，规定只能以字母开头，包含数字，字母和下划线“_”，长度最大为50个字符，对字母大小写不敏感；
用户属性值支持四种类型：字符串、数值类、bool、DateTime。

4.2 UserSetOnce

如果您要上传的用户属性只要设置一次，则可以调用UserSetOnce来进行设置，当该属性之前已经有值的时候，将会忽略这条信息：

ThinkingAnalyticsAPI.UserSetOnce(new Dictionary<string, object>()
    {
        {"USER_PROP_NUM", -50},
        {"USER_PROP_STRING", "A3"}
    });

注意：UserSetOnce设置的用户属性类型及限制条件与UserSet一致。

4.3 UserAdd

当您要上传数值型的属性时，您可以调用UserAdd来对该属性进行累加操作，如果该属性还未被设置，则会赋值0后再进行计算，可传入负值，等同于相减操作。

ThinkingAnalyticsAPI.UserAdd(new Dictionary<string, object>()
    {
        {"USER_PROP_NUM", -100.9},
        {"USER_PROP_NUM2", 10.0}
    });

注意： UserAdd 中的属性类型以及Key值的限制与UserSet一致，但Value只允许上报数值类型属性。

4.4 UserUnset

如果您需要重置用户的某个属性，可以调用UserUnset将该用户指定用户属性的值清空，此接口支持传入字符串或者列表类型的参数:

// 删除单个用户属性
ThinkingAnalyticsAPI.UserUnset("userPropertyName");

// 删除多个用户属性
List<string> listProps = new List<string>();
listProps.Add("aaa");
listProps.Add("bbb");
listProps.Add("ccc");

ThinkingAnalyticsAPI.UserUnset(listProps);

4.5 UserDelete

如果您要删除某个用户，可以调用UserDelete将这名用户删除，您将无法再查询该名用户的用户属性，但该用户产生的事件仍然可以被查询到。

ThinkingAnalyticsAPI.UserDelete();

5. 自动采集事件

如果在配置 SDK 时，勾选了Auto Track 选项，SDK 会自动记录：

ta_app_start，即游戏启动事件，每次用户获得焦点（即在游戏中）触发
ta_app_end，游戏关闭事件，当游戏进入Pause状态时触发，会附加#duration属性，记录本次游戏时长（单位是秒）

1.1.0 版本开始，可以通过接口调用的方式采集安装事件：

// 采集 APP 安装事件
ThinkingAnalyticsAPI.TrackAppInstall();

ta_app_install，游戏安装事件，安装事件只会在用户在安装后首次打开APP时启动，用户升级APP不会触发，用户删除后重装APP会再次触发该事件。

6. 其他配置选项

6.1 获取设备ID

SDK在初始化完成后，会自动生成设备ID，并记录在本地缓存，对于同一应用/游戏，一台设备的设备ID是不变的，可以调用GetDeviceId()获取设备ID：

ThinkingAnalyticsAPI.GetDeviceId();

// 以设备ID作为访客ID
// ThinkingAnalyticsAPI.Identify(ThinkingAnalyticsAPI.GetDeviceId());

6.2 延迟上报

如果您勾选了 Postpone Track 选项，意味着所有的上报请求（包括用户属性设置和事件追踪）都会先被缓存，直到您主动调用以下方法:

ThinkingAnalyticsAPI.StartTrack();

当这个接口被调用后，数据才会开始上报，在该接口调用前已产生的数据，在上报时，会重新设置的用户ID并加入公共属性。因此在调用StartTrack()前设置用户ID与公共属性，可以对所有数据都生效，适合需要设置访客ID，公共属性的场景：

//设置访客ID
ThinkingAnalyticsAPI.Identify(ThinkingAnalyticsAPI.GetDeviceId());

//设置公共属性
Dictionary<string, object> superProperties = new Dictionary<string, object>()
    {
        {"SERVER", 0},
        {"CHANNEL", "A3"}
    };
ThinkingAnalyticsAPI.SetSuperProperties(superProperties);

//调用上报启动接口
ThinkingAnalyticsAPI.StartTrack();

6.3 暂停/停止数据上报

在2.1.0版本中，新增了停止SDK上报数据的功能，一共有两类停止SDK上报的接口：

暂停SDK上报（EnableTracking）

您可能希望在一些场景下，暂时停止SDK的数据采集以及上报，比如用户处于测试环境中、或者用户登录了一个测试账号，此时您可以调用下列接口，暂时停止SDK的上报。

您可以通过某一实例（包括主要实例以及轻实例）调用EnableTracking，传入false来暂停SDK的上报，该实例已经设置的#distinct_id、#account_id、公共属性等将保留；该实例已经采集但还未上报成功的数据将继续尝试上报；后续该实例不能采集以及上报任何新数据、不能设置访客ID、账户ID以及公共属性等，但是可以读取该实例已经设置的公共属性和设备ID、访客ID、账号ID等信息。

实例的停止状态将会被保存在本地缓存，直到调用EnableTracking、传入true，SDK实例将会重新恢复数据采集以及上报，需要注意轻实例因为不进行缓存，因此每次打开APP后，轻实例的暂停状态不会被保留，将重新开启上报。

// 暂停默认实例的上报，已缓存数据和已经设置的信息不被清除
ThinkingAnalyticsAPI.EnableTracking(false);

// 恢复默认实例的上报
ThinkingAnalyticsAPI.EnableTracking(true);

停止SDK上报（OptOutTracking）

在一些特殊场景下，您可能需要完全停止SDK的功能，比如在适用GDPR的地区，用户选择不提供数据采集权限，则您可以调用如下接口完全关闭SDK的功能。

OptOutTracking只能通过主要实例调用，与EnableTracking的最大区别在于，其将会清空该实例的本地缓存，包括本实例的访客ID，账号ID，公共属性，以及未上报的数据队列。之后再关闭该实例的采集和上报功能。

// 停止默认实例的上报, 并清空本地缓存
ThinkingAnalyticsAPI.OptOutTracking();

如果您希望关闭SDK功能的同时，删除该用户在TA集群中的用户数据，可以调用OptOutTrackingAndDeleteUser，这将会在停止SDK实例的功能前，上报一条 UserDelete数据，以删除该用户的用户数据。

// 停止默认实例的上报，并发送 user_del
ThinkingAnalyticsAPI.OptOutTrackingAndDeleteUser();

实例的停止状态也将保存在本地缓存，直到调用OptInTracking，后续可以继续上报，但此时相当于一个全新的实例

// 重新开启上报
ThinkingAnalyticsAPI.OptInTracking();

6.4 创建轻实例

您可以通过轻实例的方式，创建同一个APPID下的多个实例

// 创建轻实例，返回轻实例的 token （类似于 APP ID）
string lightToken = ThinkingAnalyticsAPI.CreateLightInstance();

// 为轻实例设置账号 ID
ThinkingAnalyticsAPI.login("anotherAccount", lightToken);

// 通过轻实例上报事件
ThinkingAnalyticsAPI.Track("TEST_EVENT", lightToken)

子轻量实例与父实例的APPID、上报地址以及部分设置一致，但其他信息不共享

Release Note

v1.2.0 2019/09/02

支持关闭/打开数据上报
支持暂停/继续数据上报
支持轻量级实例
修复2019.2.1f 版本设置网络类型失败
修复timeEvent 不准确问题
Android/iOS SDK 升级为2.1.0

v1.1.0 2019/08/09

支持获取设备ID
支持动态公共属性
支持安装事件采集
内嵌Android SDK 升级为2.0.2
内嵌iOS SDK 升级为2.0.1
支持上报缓存选项，用户可以选择主动调用 StartTrack() 去开始上报

v1.0.0 2019/06/20

支持访客ID 和用户账号的设置
支持事件和用户属性上报
支持 ta_app_start 和 ta_app_end 事件的自动上报
支持公共属性接口
支持 timeEvent 接口
支持多项目上报

Unity SDK 使用指南

Unity SDK 使用指南

1. 初始化 SDK

1.1 集成 SDK

多项目支持

1.2 使用 SDK

2. 设置用户 ID

a) 设置访客ID（可选）

b) 设置与清除账号 ID

3. 上传事件

3.1 上传事件

3.2 设置静态公共属性

3.3 设置动态公共属性

3.4 记录事件时长

4. 用户属性

4.1 UserSet

4.2 UserSetOnce

4.3 UserAdd

4.4 UserUnset

4.5 UserDelete

5. 自动采集事件

6. 其他配置选项

6.1 获取设备ID

6.2 延迟上报

6.3 暂停/停止数据上报

6.4 创建轻实例

Release Note

v1.2.0 2019/09/02

v1.1.0 2019/08/09

v1.0.0 2019/06/20

results matching ""

No results matching ""